Modelling structural VARs
=========================

An ``svar`` object represents a (possibly Markov-switching) **structural**
vector autoregression -- the structural form is parameterised and estimated
directly, so there is no separate "estimate a reduced form, then rotate it"
step. Almost everything else (data handling, estimation options, forecasting,
the various decompositions, fan charts, bootstrap, Bayesian estimation, adding
regime switching) works exactly as for reduced-form VARs; see
:doc:`../ReducedFormVAR_capabilities/Main Reduced form VAR Modeling` for the
full worked example. This page covers what is specific to the structural case.

The model
---------

.. math::

	A_{0}\left( r_{t}\right) y_{t}=C\left( r_{t}\right) x_{t}+A_{1}\left(
	r_{t}\right) y_{t-1}+...+A_{p}\left( r_{t}\right) y_{t-p}+\varepsilon _{t}

with :math:`r_{t}=1,2,...,h` and transition probabilities
:math:`p_{r_{t},r_{t+1}}\left( I_{t}\right)`, and structural shocks
:math:`\varepsilon_{t}\sim N\left(0,I\right)`.

- :math:`A_{0}\left(r_{t}\right)` is the contemporaneous-impact matrix. It is
  normalised to have a unit diagonal (``a0_i_i = 1``), which fixes the scale of
  each structural shock.
- :math:`A_{1},...,A_{p}` are the lag-coefficient matrices, :math:`C` the
  coefficients on the deterministic / exogenous block :math:`x_{t}` (a constant,
  any declared exogenous regressors, and lags of :math:`y`).

The estimated parameters are named by analogy with the matrices:

- ``a0(row,col)`` -- the contemporaneous coefficients (off-diagonal entries of
  :math:`A_{0}`; the diagonal is fixed at 1);
- ``a1(row,col)``, ..., ``ap(row,col)`` -- the lag coefficients (``a(row,col)``,
  with the lag index omitted, refers to all lags);
- ``c(row,col)`` -- the coefficients on the exogenous / constant block;

where ``row`` and ``col`` are integers or endogenous-variable names, e.g.
``a0(R,PAI)`` or ``a1(2,3)``.

Creating an SVAR
----------------

::

	endog = {'PAIOIL','GROWTH','PAI','R','EXRATE'};

	exog  = {};

	nlags = 4;

	const = true;

	mdl = svar(endog, exog, nlags, const);

(The constructor signature mirrors ``rfvar``'s:
``svar(varlist, exog, nlags, constant, markov_chains)``, the last two being
optional.)

Identification
--------------

A structural VAR with :math:`n` endogenous variables has :math:`n(n-1)/2` more
free parameters in :math:`A_{0}` than the data can pin down, so identifying
restrictions must be supplied. In RISE these are ordinary parameter
restrictions on ``a0`` (and, if you wish, on the lag coefficients), passed to
``estimate`` in the linear-restrictions cell array -- the same mechanism used
for block-exogeneity restrictions in the reduced-form VAR chapter.

A **recursive** (Cholesky-type) identification orders the variables and zeroes
the entries of :math:`A_{0}` above the diagonal, so that variable 1 is not
affected contemporaneously by any other shock, variable 2 only by shock 1, and
so on::

	linres = {};
	for ii = 1:numel(endog)
	    for jj = ii+1:numel(endog)
	        linres{end+1,1} = sprintf('a0(%s,%s)=0', endog{ii}, endog{jj}); %#ok<SAGROW>
	    end
	end

Exclusion (zero) restrictions can equally be imposed one at a time, e.g.
``'a0(PAIOIL,R)=0'`` ("the policy-rate shock has no contemporaneous effect on
oil-price inflation"), and you can mix them with restrictions on the lag
coefficients (``'a1(PAIOIL,GROWTH)=0'``, ...).

.. todo::

   Document sign-restriction and long-run identification of SVARs, and the
   over-identified case (testing the restrictions).

Estimation
----------

Estimation is exactly as for a reduced-form VAR -- pass the model, a database
of :doc:`time series <../DataManagement/Data Management>`, the estimation
sample, an (optional) prior, and the identifying restrictions::

	data_range = {db.GROWTH.start, db.GROWTH.finish};

	mdlest = estimate(mdl, db, data_range, [], linres);     % classical

	% Bayesian: build a prior with svar.prior_template(), e.g.
	var_prior        = svar.prior_template();
	var_prior.type   = 'sz';                                % Sims-Zha prior
	prior            = struct('var', var_prior);
	mdlest_bayes     = estimate(mdl, db, data_range, prior, linres);

After estimation, inspect the structural form with::

	print_structural_form(mdlest)

Impulse responses, variance and historical decompositions, forecasting
----------------------------------------------------------------------

Because the model is already structural, no identification function is needed:
the shock names are simply the structural shocks (one per endogenous variable,
by RISE's naming convention), and ``irf`` / ``variance_decomposition`` /
``historical_decomposition`` / ``forecast`` are called directly::

	myirfs = irf(mdlest);                       % all shocks, default horizon
	myirfs = irf(mdlest, shock_names, 40);

	vd = variance_decomposition(mdlest);

	hd = historical_decomposition(mdlest);

	fkst = forecast(mdlest, db, '2003Q1');

For plotting (``quick_irfs``, ``plot_fanchart``, ``plot_decomp``, ...),
parameter uncertainty via ``bootstrap``, Bayesian posterior sampling, fan
charts of the decompositions and IRFs, and conditional forecasting, see the
reduced-form VAR chapter -- the calls are identical, with ``a0``/``a1``/...
parameters in place of the reduced-form ``b1``/``b2``/... ones, and without the
extra ``Rfunc`` (identification) argument.

Adding regime switching
-----------------------

As for the reduced-form VAR, pass a Markov-chain structure as the fifth
argument and list the parameters it controls -- for an SVAR these are typically
``a0`` (switching contemporaneous transmission) and/or ``a1``, ..., ``ap``::

	mc = struct();
	mc.name                      = 'policy';
	mc.number_of_states          = 2;
	mc.controlled_parameters     = {'a0(R,:)'};
	mc.endogenous_probabilities  = [];
	mc.probability_parameters    = [];

	mdl = svar(endog, exog, nlags, const, mc);

Time-varying transition probabilities are specified exactly as in the
reduced-form VAR chapter (an ``endogenous_probabilities`` definition plus the
``probability_parameters`` that enter it), and the switching parameters are
given priors through ``prior.nonvar``.

Proxy / instrumental SVARs are handled by the related :doc:`proxy SVAR
<../Proxy_SVAR_capabilities/Main Proxy SVAR Modeling>` object, and panels of
(structural) VARs by the :doc:`panel VAR <../PanelVAR_capabilities/Main Panel VAR Modeling>` object.

Technical documentation for svar objects
----------------------------------------

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   svar_properties_methods